Determining Dash Positions (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 3 - Geometric Styles / Using Geometric Styles

Determining Dash Positions
A restriction of the QuickDraw GX dashing architecture is that each dash must be the same shape. There may be a situation where you'd like to dash a contour and have the dashes change as they progress along the contour.
To help you create the appearance of a dashed contours where the dashes change, QuickDraw GX provides the GXGetShapeDashPositions function. This function returns a list of mappings that identify the position and rotation of each dash on a shape.
By placing shapes in a picture using this list of mappings, you can give the effect of a contour with changing dashes.
As an example, the sample functions in this section show you how to create a picture of a clock. The CreateDashedCircle sample function in Listing 3-17 creates a circle with 12 dashes, each of which appears where a number would appear on a clock.
Listing 3-17 Creating a circle with 12 dashes
void CreateDashedCircle(void)
{
   gxShape  aCircleShape, aSquareShape;

   static gxRectangle circleBounds = {ff(50), ff(50), 
                                      ff(180), ff(180)};
   
   static gxRectangle squareBounds = {-ff(10), -ff(10), 
                                      ff(10),  ff(10)};
   
   gxDashRecord theDashRecord;
   
   aCircleShape = NewArc(&circleBounds, ff(30), ff(350), false);
   GXSetShapeFill(aCircleShape, gxClosedFrameFill);
   GXSetShapePen(aCircleShape, ff(60));

   aSquareShape = GXNewRectangle(&squareBounds);
   GXSetShapeFill(aSquareShape, gxEvenOddFill);
      
   theDashRecord.attributes = gxAutoAdvanceDash | gxLevelDash;  
   theDashRecord.dash = aSquareShape;
   theDashRecord.advance = ff(34); 
   theDashRecord.phase = 0; 
   theDashRecord.scale = ff(60); 

   GXSetShapeDash(aCircleShape, &theDashRecord);
   GXDisposeShape(aSquareShape);
   
   GXDrawShape(aCircleShape);
   
   GXDisposeShape(aCircleShape);
}
This sample function creates a square shape using the GXNewRectangle function to use as a dash for a circle shape created using the library function NewArc.
The result of this function is shown in Figure 3-73.
Figure 3-73 Dash positions for a clock

To replace the square dashes with numbers, the sample function in Listing 3-18 calls the GetDashPositions function to obtain an array of mappings that identify the position and rotation of each dash. (Notice that the dashes are not rotated in this case since the level dash attribute is set.)
The sample function in Listing 3-18 then creates a picture and adds to it text shapes containing the numbers 1 through 12. Each time text is added to the picture, its mapping is set to be the next mapping in the array of dash positions.
Listing 3-18 Creating a clock shape
void CreateAClock(void)
{
   gxShape  aCircleShape, aTextShape, aSquareShape, aPicture;

   static gxRectangle circleBounds = {ff(50), ff(50), 
                                      ff(180), ff(180)};
   
   static gxRectangle squareBounds = {-ff(10), -ff(10), 
                                      ff(10),  ff(10)};
   
   static gxPointtextPosition = {ff(0), ff(0)};
   
   static char* numbers[] = {" 1", " 2", " 3", " 4", " 5", " 6", 
                             " 7", " 8", " 9", "10", "11", "12"};
      
   gxDashRecord theDashRecord;
   
   long numberOfDashes, count;
   gxMapping dashMappings[12];

   /* Create the dashed circle from the previous example. */

   aCircleShape = NewArc(&circleBounds, ff(30), ff(350), false);
   GXSetShapeFill(aCircleShape, gxClosedFrameFill);

   aSquareShape = GXNewRectangle(&squareBounds);
   GXSetShapeFill(aSquareShape, gxEvenOddFill);
      
   theDashRecord.attributes = gxAutoAdvanceDash | gxLevelDash;  
   theDashRecord.dash = aSquareShape;
   theDashRecord.advance = ff(34); 
   theDashRecord.phase = GXFloatToFract(0.0); 
   theDashRecord.scale = ff(60); 

   GXSetShapeDash(aCircleShape, &theDashRecord);
   GXSetShapePen(aCircleShape, ff(60));

   /* Find the dash positions. */
   numberOfDashes = GXGetShapeDashPositions(aCircleShape,
                                            dashMappings);
   GXDisposeShape(aCircleShape);
   GXDisposeShape(aSquareShape);
   
   /* Create a picture with numbered text shapes. */

   aTextShape = GXNewText(1, (unsigned char*) " 1",
                          &textPosition);
   GXSetShapeFill(aTextShape, gxEvenOddFill);
      
   aPicture = GXNewShape(gxPictureType);
   GXSetShapeAttributes(aPicture, gxUniqueItemsShape);
   for (count = 0; count <= numberOfDashes; count++) {
      GXSetShapeMapping(aTextShape, dashMappings[count]);
      GXSetText(aTextShape, 2, numbers[count], &textPosition);
      AddToShape(aPicture, aTextShape);
   }
   GXDisposeShape(aTextShape);
   
   GXDrawShape(aPicture);
   
   GXDisposeShape(aPicture);
}
The result of the CreateAClock sample function is depicted in Figure 3-74.
Figure 3-74 A clock shape

This sample function uses some concepts from other parts of QuickDraw GX. For more information about

mappings, see the chapter "Transform Objects" in Inside Macintosh: QuickDraw GX Objects.
pictures and adding elements to them, see Chapter 6, "Picture Shapes."
typographic shapes, see Inside Macintosh: QuickDraw GX Typography.